Creating Tracks and Media Structures2

The Movie Toolbox provides several functions that allow your application to create new movie tracks and media structures and to dispose of existing tracks and media structures. You use these functions when you are creating a new movie or when you are editing an existing movie.

You can use the NewMovieTrack function to create a new track for a specified movie. Conversely, you can use the DisposeMovieTrack function to dispose of an existing track.

Your application can create a new media for a track by calling the NewTrackMedia function. You can use the DisposeTrackMedia function to dispose of an existing media.

NewMovieTrack

You can create movie tracks by calling the NewMovieTrack function. Immediately after creating a new track, you should call the NewTrackMedia function to create a media for the track--a track without a media is of no use.

Note that when you add a track to a movie, the Movie Toolbox automatically adjusts the display rectangle of the movie. You may want to detect these changes by calling the GetMovieBox function (described on GetMovieBox ) so that you can adjust the size of the movie's display window.



 
pascal Track NewMovieTrack (Movie theMovie, Fixed width, 

                                         Fixed height, short trackVolume);

theMovie: Specifies the movie for this operation. Your application obtains this movie identifier from such functions as NewMovie , NewMovieFromFile , and NewMovieFromHandle (described on NewMovie , NewMovieFromFile , and NewMovieFromHandle , respectively).
width: Specifies a fixed number denoting the display width of the track, in pixels. Along with the height parameter, this parameter defines the track's display rectangle.
height: Specifies a fixed number denoting the display height of the track, in pixels.; Together, the height and width parameters define the track's display rectangle. The upper-left corner of this rectangle lies at (0,0) in the movie's rectangle. The height and width parameters therefore establish the lower-right corner of the track's display rectangle. If you are creating a track that is not displayed, such as a sound track, set the height and width parameters to 0.
trackVolume: Specifies the volume setting of the track as a 16-bit, fixed-point number. The high-order 8 bits specify the integer portion; the low-order 8 bits specify the fractional part. Volume values range from -1.0 to 1.0. Negative values play no sound but preserve the absolute value of the volume setting. Set this parameter to kFullVolume to play the track at its full, natural volume. Set this parameter to kNoVolume to set the volume to 0.

DESCRIPTION

The NewMovieTrack function returns a track identifier. If the function cannot create the track, it sets the returned identifier to nil .

ERROR CODES

invalidMovie

-2010

This movie is corrupted or invalid

Memory Manager errors

DisposeMovieTrack

The DisposeMovieTrack function removes a track from a movie.



 
pascal void DisposeMovieTrack (Track theTrack);

theTrack: Specifies the track for this operation. Your application obtains this track identifier from such Movie Toolbox functions as NewMovieTrack and GetMovieTrack (described on NewMovieTrack and GetMovieTrack , respectively).

DESCRIPTION

When you remove a track from a movie, the Movie Toolbox also removes the corresponding media from the movie.

SPECIAL CONSIDERATIONS

Your application should not call this function as part of the process of disposing of a movie. When you dispose of a movie by calling the DisposeMovie function (described on DisposeMovie ), the Movie Toolbox disposes of all the movie's tracks and their associated media structures.

ERROR CODES

invalidTrack	-2009	This track is corrupted or invalid
trackNotInMovie	-2030	This track is not in this movie

NewTrackMedia

After you have created a new track, you can create a media for the track by calling the NewTrackMedia function. The media refers to the actual data samples used by the track.



 
pascal Media NewTrackMedia (Track theTrack, OSType mediaType, 

                                          TimeScale timeScale, Handle dataRef, 

                                          OSType dataRefType);

theTrack: Specifies the track for this operation. Your application obtains this track identifier from such Movie Toolbox functions as NewMovieTrack (described on NewMovieTrack ).
mediaType: Specifies the type of media to create. The Movie Toolbox uses this value to find the correct media handler for the new media. If the toolbox cannot locate an appropriate media handler, it returns an error. The following types are available:
timeScale: Defines the media's time coordinate system.
dataRef: Specifies the data reference. This parameter contains a handle to the information that identifies the file that contains this media's data. The type of information stored in that handle depends upon the value of the dataRefType parameter.; If you are creating a new media that refers to existing media data, you can use the GetMediaDataRef function (described on GetMediaDataRef ) to obtain information about the existing data reference. You can then supply information about that reference to this function.; Set this parameter to nil to use the file that is associated with the movie or if the movie does not have a movie file. For example, if you have created the movie using the CreateMovieFile function (described on CreateMovieFile ) or the NewMovieFromFile function (described on NewMovieFromFile ), the Movie Toolbox assumes that the movie's data resides in the file specified at that time. If you have created the movie using the NewMovieFromScrap or NewMovie functions (described on NewMovieFromScrap and NewMovie , respectively), the movie does not have a movie file.
dataRefType: Specifies the type of data reference. If the data reference is an alias, you must set this parameter to rAliasType ('alis' ), indicating that the reference is an alias. See Inside Macintos h: Files for more information about aliases and the Alias Manager.; If you are creating a new media that refers to existing media data, you can use the GetMediaDataRef function (described on GetMediaDataRef ) to obtain information about the existing data reference. You can then supply information about that reference to this function.; Set this parameter to nil to use the file that is associated with the movie or if the movie does not have a movie file. For example, if you have created the movie using the CreateMovieFile function (described on CreateMovieFile ) or the NewMovieFromFile function (described on NewMovieFromFile ), the Movie Toolbox assumes that the movie's data resides in the file specified at that time. If you have created the movie using the NewMovieFromScrap or NewMovie functions (described on NewMovieFromScrap and NewMovie , respectively), the movie does not have a movie file.

DESCRIPTION

The NewTrackMedia function returns a media identifier. If the function cannot create the new media, it sets this returned value to nil .

ERROR CODES

cantFindHandler	-2003	Cannot locate a handler
cantOpenHandler	-2004	Cannot open a handler
noMediaHandler	-2006	Media has no media handler
invalidTrack	-2009	This track is corrupted or invalid
invalidTime	-2015	This time value is invalid

Memory Manager errors

DisposeTrackMedia

The DisposeTrackMedia function removes a media from a track. This function does not remove the track from its movie.



 
pascal void DisposeTrackMedia (Media theMedia);

theMedia: Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on NewTrackMedia and GetTrackMedia , respectively).

SPECIAL CONSIDERATIONS

Your application should not call the DisposeTrackMedia function as part of the process of disposing of a movie. When you dispose of a movie by calling DisposeMovie , the Movie Toolbox disposes of all the movie's tracks and their associated media structures.

ERROR CODES

invalidMedia

-2008

This media is corrupted or invalid

	VideoMediaTyp`e`	Video media
	SoundMediaTyp`e`	Sound media
	TextMediaTyp`e`	Text media